IPM

IPM (IDL Package Manager) allows you to create, install, update, and remove IDL packages that are a collection of files and/or folders compressed into a ZIP file. The package can contain any combination of IDL pro code, IDL save files, and/or IDL DLMs. It also contains an idlpackage.json file that describes the package.

Packages are installed to the directory defined by the new IDL_PACKAGE_PATH preference, and the IDL path is automatically updated to include the new files.

Actions

For details on the actions you can do with IPM, click on a link below to see the syntax, and a description of each action.

The Package File

A valid IDL package must contain an idlpackage.json file at the top level inside the .zip file. Do not rename the .json file. The structure of the file must be valid JSON and should have a structure similar to the following:

{

"Name": "IDLMathLib",

"Version": "1.9.13",

"Author": "Natasha Fatale",

"Date": "Sep 2017",

"Dependencies": [

{

"Name": "IDL",

"Version": "^8.6"

{

"Name": "Squirrel",

"Version": ">5.10",

"URL": "http://github.com/Fatale/Squirrel"

}

]

}

The only field that is required is the "Name" field; all others are optional. If the package is hosted on GitHub, the "Version" listed in the idlpackage.json file should match the version tag in the GitHub repository. Also, when hosting the package on GitHub, you need to create a GitHub "release," which is described in the GitHub Help at https://docs.github.com/en/github/administering-a-repository/managing-releases-in-a-repository.

If more than one dependency is needed, they need to be in a JSON list or array; a single dependency can be in a single JSON object. It is recommended that you use semantic versioning when you specify a version for a dependency. The URL value in a dependency must be a fully qualified location.

Semantic Versioning

Basic Ranges

A basic range has the form >1.2.3. This tells IDL to use the latest version that is after version 1.2.3.

Note: No spaces are allowed between the operator and the version number. Also, no spaces are allowed in the version string itself.

IPM supports the following operators:

= : equal (this is the default when no operator is supplied)

> : greater than

< : less than

>= : greater than or equal to

<= : less than or equal to

Combined Ranges

A space between two basic ranges means both ranges must be satisfied. To use range 1 OR range 2, use " || " between two ranges.

">=1.2 <1.6" means any version greater than or equal to 1.2 but also less than 1.6.

">=1.5 || 1.3" means any version greater than or equal to 1.5, but also allow version 1.3

Major Ranges

The caret (^) comparison operator is for major level changes, i.e., the major version must be the same. This is useful when comparisons of versions as a major change is breaking.

^1.2.3 means any version greater than or equal to 1.2.3, but less than 2.0.0 (>=1.2.3 <2.0.0)

Minor Ranges

The tilde (~) comparison operator is for patch level ranges, i.e., both the major and minor versions must be the same.

~1.2.3 means any version greater than or equal to 1.2.3, but less than 1.3.0 (>=1.2.3 <1.3.0)

IPM CREATE

CREATE allows you to create or update a .zip file that can be distributed as an IDL package.

Note: You must supply a NAME to be able to create a valid IDL package. You can specify it with the NAME keyword, or by supplying a valid idlpackage.json file within the folder being zipped.

Examples

The following creates a new ZIP file that includes all the files in the MyMathLib folder. The resulting ZIP file will be found at: C:\MyIDL\ehMathLib.zip.

IPM, /CREATE, 'C:\MyIDL\MyMathLib', NAME='ehMathLib', VERSION='1.0'

The following assumes there is a valid idlpackage.json file residing in the MyStatsLib folder. The VERSION within the json file will be updated to 1.2.

IPM, /CREATE, 'C:\MyIDL\MyStatsLib', VERSION='1.2'

Syntax

IPM, /CREATE, Folder [, Keywords=value]

Arguments

Folder

Set this argument to a scalar string giving the full path to a local folder. The entire contents of this folder will be copied into a ZIP file. If an idlpackage.json file does not currently exist in the folder and the NAME keyword is specified, IPM will create one. If an idlpackage.json file does exist in the folder, keywords can be used to update the idlpackage.json file.

Keywords

AUTHOR

Set this to the name of the package's author. This value will be stored in the idlpackage.json file; it will overwrite any current author value in the file if one exists.

DATE

Set this to a string denoting the date of creation of the current version of the package. This value will be stored in the idlpackage.json; it will overwrite any current date value in the file if one exists.

DEPENDENCIES

Set this keyword to a hash containing the json that describes any dependencies your package requires.

NAME

Set this to the name of the package to create. If an idlpackage.json file exists in the folder where you are creating the package, the NAME specified in the json file will be used.

Note: If an idlpackage.json file does not currently exist, then NAME must be specified.

OUTPUT

Set this keyword to an IDL variable that will contain a string containing any informational or error messages that are printed to the console during execution. This is useful when a program wants to be able to parse the output of the IPM operation.

PACKAGE_INFO

If set to a hash or an ordered hash, all the key/value pairs contained will be added to the idlpackage.json file during package creation.

QUIET

If set, does not print any messages to the console. The default is to print messages to the console.

URL

Set this to the full URL that can be used to find this package. For example, https://github.com/envi-idl/mgunit.zip. This value will be stored in the idlpackage.json file and will overwrite any current value in the file, if one exists.

VERSION

Set this to a string denoting the current version of the package. This value will be stored in the idlpackage.json; it will overwrite any current date value in the file if one exists.

ZIP_FILE

Set this to the full path and name of the ZIP file in which to create the new IPM package. If not specified, the name of the package will be the name either from the NAME keyword or the NAME supplied in the idlpackage.json. The ZIP file will be located one level above the specified folder.

IPM GET

GET allows you to download the ZIP files for a package, but does not unzip or install them. This can be useful if you know you only want a small subset of a given package and will manually unzip the files you desire.

Example

The following will download the ZIP files for mgunit.zip along with any ZIP files for dependency packages, but will not unzip any of them. The variable files will then contain the full path to all the downloaded zip files.

IPM, /GET, 'http://github.com/envi-idl/mgunit.zip', FILE=files

Syntax

IPM, /GET, Package [, Keywords=value]

Arguments

Package

Set this argument to a scalar string giving the location and name of an IDL package. This can be a complete URL to a location on the local file system, a URL to a location on the web, or sufficient package information to find the package on a repository such at GitHub.

Keywords

FILE

If this is set to an IDL variable, it will return an array that contains the full path to all the downloaded ZIP files, including those of any dependency packages.

OUTPUT

PACKAGE_FOLDER

By default, IPM installs new packages in the !PACKAGE_PATH directory. If PACKAGE_FOLDER is set to the full path of an existing folder, the package will be placed in this folder instead.

Note: If PACKAGE_FOLDER is specified, IDL's path is not automatically updated to include the new directories, this must be done manually.

QUIET

If set, does not print any messages to the console. The default is to print messages to the console.

SKIP_DEPENDENCIES

Set this keyword to 1 to ignore, and to not download, any dependencies listed in the given package. The default is to download any dependencies listed in the package.

TYPE

Set this keyword to the type of package being installed. If not set, IPM will attempt to determine the type by examining the contents of the package URL. The choices are:

localfile
remotefile
github

VERSION

Set this keyword to the version to obtain. Some semantic versioning is accepted. See Semantic Versioning for details on the versioning used by the IDL Package Manager.

IPM INSTALL

INSTALL allows you to download and install an IDL package. The packages will be unzipped into a folder underneath the !PACKAGE_PATH directory. The new directory name will be taken from the name of the package being installed. By default, any package dependencies will also be downloaded and installed. The IDL path will be updated to include the new installed files.

Example

The following will download and install the zip files for mgunit.zip, along with any zip files for dependency packages. The IDL path will then be updated.

IPM, /INSTALL, 'http://packages.idldev.com/mgunit.zip'

Syntax

IPM, /INSTALL, Package [, Keywords=value]

Arguments

Package

Keywords

FILE

If this is set to an IDL variable, it will return an array that contains the full path to all the downloaded ZIP files, including those of any dependency packages.

KEEP_ZIP

Set this keyword to keep the ZIP file after installing the package. By default, any downloaded ZIP file will be deleted after it is unpacked and installed.

OUTPUT

PACKAGE_FOLDER

By default, IPM installs new packages in the !PACKAGE_PATH directory. If PACKAGE_FOLDER is set to the full path of an existing folder, the package will be placed in this folder instead.

Note: If PACKAGE_FOLDER is specified, IDL's path is not automatically updated to include the new directories, this must be done manually.

QUIET

If set, does not print any messages to the console. The default is to print messages to the console.

SKIP_DEPENDENCIES

Set this keyword to 1 to ignore, and to not download, any dependencies listed in the given package. The default is to download and install any dependencies listed in the package.

TYPE

Set this keyword to the type of package being installed. If not set, IPM will attempt to determine the type by examining the contents of the package URL. The choices are:

localfile
remotefile
github

VERSION

Set this keyword to the version to obtain. Some semantic versioning is accepted. See Semantic Versioning for details on the versioning used by the IDL Package Manager.

IPM LIST

LIST allows you to get a basic list of the packages currently installed. If NAME is not supplied, LIST will list all the currently installed packages. If NAME is supplied, LIST will list only the information for the specified package.

Example

IPM, /LIST

IDL prints:

Number of installed packages: 2

Name: MyMathLib, Version: 3.14

Name: MyStatsLib, Version: 5.10

Syntax

IPM, /LIST, Name [, Keywords=value]

Arguments

Name

Set this argument to a scalar string giving the name of the installed package.

Keywords

OUTPUT

QUIET

If set, does not print any messages to the console. The default is to print messages to the console.

IPM QUERY

QUERY allows you to see all the details of a given package.

Example

IPM, /QUERY, 'MyMathLib'

IDL prints:

{

"Name": "MyMathLib",

"Version": "3.14",

"Author": "Boris",

"Dependencies": [

{

"Name": "IDL",

"Version": "^8.7"

}

]

}

Syntax

IPM, /QUERY, Name [, Keywords=value]

Arguments

Name

Set this argument to a scalar string giving the name of the installed package.

Keywords

INFO

If set to an IDL variable, this keyword will return an ordered hash containing all the information known about the package.

OUTPUT

QUIET

If set, does not print any messages to the console. The default is to print messages to the console.

IPM REMOVE

REMOVE allows you to remove packages. Removing a package deletes the folder in which the package resides and updates the IDL path to no longer look in that folder.

Example

The following will delete the folders containing the two packages and updates the IDL path.

IPM, /REMOVE, ['MyMathLib', 'MyStatsLib']

Syntax

IPM, /REMOVE, Name [, Keywords=value]

Arguments

Name

Set this to a String or String array denoting the name(s) of the packages you wish to remove.

Keywords

OUTPUT

QUIET

If set, does not print any messages to the console. The default is to print messages to the console.

IPM UPDATE

UPDATE allows you to update the contents of a given package. If a suitable update is found, the current package will be removed and the new package will then be installed. When UPDATE is called, the dependency tree is searched. If a conflict is found, a message will be printed and no update will occur. In this case, you must manually update each dependent library as needed. If version information cannot be found for a given package, a message will be printed and no update will occur.

Examples

The following will attempt to update MyMathLib from the current version to version 3.2

IPM, /UPDATE, 'MyMathLib', VERSION='3.2'

IDL prints:

Package "MyMathLib" was removed

Package: MyMathLib, Version: 3.2 installed

The following will attempt to update MyStatsLib to the latest version. But in this case a dependency conflict occurs.

IPM, /UPDATE, 'MyStatsLib'

IDL prints:

Cannot update. Conflicts exist with dependencies:

Conflict in package "StatsHelper", Version: 1.2 is currently installed but "MyStatsLib" requires version: ^1.4.1

It is now up to you to decide whether or not it is safe to update StatsHelper to the needed version.

Syntax

IPM, /UPDATE, Name [, Keywords=value]

Arguments

Name

Set this argument to a scalar string giving the name of the installed package.

Keywords

OUTPUT

QUIET

If set, does not print any messages to the console. The default is to print messages to the console.

VERSION

Set this keyword to the version to obtain. If no version is specified, IDL will attempt to update to the lastest version found. Some semantic versioning is accepted. See Semantic Versioning for details on the versioning used by the IDL Package Manager.

Version History

8.7.1

Introduced